7.4.3 ユーザーのオンチェーンアドレスを取得する

#簡単な説明: ユーザーのオンチェーンアドレスを取得します (存在しない場合は作成します)。

リクエスト方法：POST
リクエストインターフェイス: https://gateway-domain/wallet-trade-merchant/merchant/user/get-address ・リクエストメディアタイプ(JSONデータ形式)Content-Type: application/json

クエリパラメータ

パラメータ名	タイプ	必須	パラメータの意味	パラメータの説明
`merchantId`	`int64`	はい	販売者 ID
`userId`	`string`	はい	ユーザーID	販売者のローカルユーザーの一意の ID
`network`	`string`	はい	メインネット	TRON、BSC、POLYGON、ETHEREUM をサポート (ドキュメント 7.4.2 から入手可能)
`key`	`string`	はい	販売者キー	プラットフォームに割り当てられたマーチャントキー
`sign`	`string`	はい	署名リファレンス (署名方法)	詳細については、ルールに署名する方法を参照してください。

JSON サンプルをリクエスト

{
  "merchantId": "302992856974",
  "userId": "77",
  "network": "TRON",
  "key": "9yUreYgTRtit39Dy",
  "sign": "3876e3b40ce4938c3123f07cd5aecb8c"
}

応答 json の例

{
  "code": 0,
  "data": {
    "address": "TMWFqTEZMDRxNzyfudFBw4rn7QFvMt4kSN",
    "merchantId": 308116064181,
    "network": {
      "avgBlockSecond": 3,
      "coinTotal": 2,
      "collectionNetworkConfirm": 3,
      "displayName": "Tron",
      "estimatedMinute": 1,
      "isDefault": null,
      "level": null,
      "logo": "https://dx-public-download.s3.ap-southeast-1.amazonaws.com/blockchain-logo/tron.png",
      "masterCoin": "TRX",
      "name": "TRON",
      "networkType": "TRON",
      "queryBaseUrl": "https://nile.tronscan.org/",
      "withdrawalNetworkConfirm": 3
    },
    "userId": "33"
  },
  "success": true,
  "message": null
}

応答データパラメータの説明

パラメータ名	タイプ	パラメータの意味	備考
`merchantId`	`int64`	販売者 ID
`userId`	`string`	ユーザーID	販売者のローカルユーザーの一意の ID
`address`	`string`	チェーンアドレス	ユーザーのチェーンアドレス
`network`	`object`	チェーンメインネットワーク情報
━ 名前	`string`	メインネット名
└ クエリベースURL	`string`	オンチェーンクエリ URL
└ コレクションネットワーク確認	`int64`	リチャージネットワーク確認数
└出金ネットワーク確認	`int64`	出金ネットワーク確認数
└ コイン合計	`int64`	コインの数
└ マスターコイン	`string`	メインチェーン通貨
└ ネットワークタイプ	`string`	メインネットワークタイプ (クライアントがアドレスタイプを保存したい場合は、このフィールドを使用してください)
└ マスターコイン	`string`	メインチェーン通貨
└ avgBlockSecond	`num`	平均ブロック時間 (秒)
└ 推定分	`num`	デポジット到着予定時間 (分)
└ 表示名	`string`	メインネットの表示名
━ ロゴ	`string`	ロゴアドレス

コールバック通知

ユーザーのアドレスが支払いを受け取り、注文が処理されると、システムは販売者によって設定されたデフォルトのコールバックアドレスに通知メッセージを送信します。

コールバックアドレスの構成

このインターフェイスは、リクエストパラメーターによる notifyUrl の指定をサポートしていません。システムは、販売者のバックエンドによって設定されたデフォルトのコールバックアドレスをコールバックします。デフォルトのコールバックアドレスは、作成時に販売者によって提供され、運用管理のバックグラウンドで維持できます。

コールバックリクエストメソッド

HTTP メソッド

POST

コンテンツタイプ

application/json

コールバックデータの例

コールバックデータは資金源に応じて次の 3 つの状況に分けられます。

シナリオ 1: チェーン (他のウォレット) を介してこのアドレスに送金します

オンチェーン転送シナリオは、blockchain オンチェーントランザクション情報を返します。

{
  "amount": "6",
  "bizType": "PAYMENT_TRANSFER",
  "blockchain": {
    "network": "TRON",
    "receiverAddress": "TMWFqTEZMDRxNzyfudFBw4rn7QFvMt4kSN",
    "senderAddress": "TPutFhYUQnrRxHSmKVwjp55vgk9QY6r5nS",
    "txId": "8265e6b65d8aad4727b55f79880941c1e22df54278a1f78b28d760eb7328a0d2",
    "txIndex": 0
  },
  "currency": "USDT",
  "merchantActualAmount": "38.86",
  "merchantCurrency": "CNY",
  "merchantId": 308116064181,
  "merchantPaidAmount": "38.86",
  "merchantUserId": "33",
  "notifyTime": 1783671086642,
  "orderCreateTime": 1783671075931,
  "orderId": "566708436246981",
  "status": "SUCCESS",
  "type": "PAYMENT",
  "userAmount": "6",
  "userCurrency": "USDT",
  "userReceivableAmount": "6",
  "sign": "b0d2d52d8dc41af9373431fc8b2b2d6a"
}

シナリオ 2: 内部ウォレット経由でこのアドレスに送金

内部ウォレットの支払いシナリオでは、支払者の walletUserId が返されます。

{
  "amount": "7",
  "bizType": "PAYMENT_TRANSFER",
  "currency": "USDT",
  "merchantActualAmount": "45.33",
  "merchantCurrency": "CNY",
  "merchantId": 308116064181,
  "merchantPaidAmount": "45.33",
  "merchantUserId": "33",
  "notifyTime": 1783671928955,
  "orderCreateTime": 1783671928956,
  "orderId": "566715422826565",
  "status": "SUCCESS",
  "type": "PAYMENT",
  "userAmount": "7",
  "userCurrency": "USDT",
  "userReceivableAmount": "7",
  "walletUserId": 3,
  "sign": "08c9b45f19709f9d4e8ffbd5bc852eb9"
}

シナリオ 3: Merchant OpenAPI を通じてこのアドレスにお金を引き出す

Merchant OpenAPI を通じて出金注文が作成され、このアドレスに出金されると、ソース出金注文情報 fromWithdraw が返されます。

{
  "amount": "8",
  "bizType": "PAYMENT_TRANSFER",
  "currency": "USDT",
  "fromWithdraw": {
    "localOrderId": "17751376202610003",
    "merchantId": 308116064181,
    "orderId": 566716344475973
  },
  "merchantActualAmount": "51.81",
  "merchantCurrency": "CNY",
  "merchantId": 308116064181,
  "merchantPaidAmount": "51.81",
  "merchantUserId": "33",
  "notifyTime": 1783672041921,
  "orderCreateTime": 1783672041922,
  "orderId": "566716348211653",
  "status": "SUCCESS",
  "type": "PAYMENT",
  "userAmount": "8",
  "userCurrency": "USDT",
  "userReceivableAmount": "8",
  "walletUserId": 2,
  "sign": "fc648e11787ccd94accd139453a3c69b"
}

**ビジネス開発のニーズを満たすために、将来、コールバックパラメーターに新しいフィールドが追加される可能性があります。新しく追加されたフィールドは、デフォルトで署名計算に参加します (署名ルールに特に指定されているフィールドを除く)。したがって、販売者システムは、フィールドの拡張による署名検証の失敗を回避するために、上位互換性を備えている必要があります。 **

コールバックパラメータの説明

パラメータ名	タイプ	参加署名	パラメータの意味	パラメータの説明
`amount`	`decimal`	はい	注文金額
`bizType`	`enum`	はい	業種	`PAYMENT_TRANSFER` に固定
`blockchain`	`object`	はい	オンチェーントランザクション情報	オンチェーン転送およびリチャージのシナリオのみが返されます。
━ ネットワーク	`String`	はい	メインネット
└ 受取人住所	`String`	はい	受信者のアドレス
└ 差出人アドレス	`String`	はい	送付先住所
└ txId	`String`	はい	トランザクションID	ブロックチェーントランザクションハッシュ
└ txインデックス	`int`	はい	トランザクションインデックス
`currency`	`String`	はい	注文通貨
`fromWithdraw`	`object`	はい	出金注文情報	OpenAPI を介してこのアドレスにお金を引き出すシナリオのみが返されます。
└ ローカルオーダーID	`String`	はい	ソース販売者の注文番号
└ 販売者 ID	`int64`	はい	ソース引き出し注文の販売者 ID
└ 注文ID	`int64`	はい	ソースプラットフォームの注文番号
`merchantActualAmount`	`decimal`	はい	販売者の実際の支払い額
`merchantCurrency`	`String`	はい	加盟店決済通貨
`merchantId`	`int64`	はい	販売者 ID
`merchantPaidAmount`	`decimal`	はい	加盟店売掛金
`merchantUserId`	`String`	はい	販売者のユーザー ID	アドレス取得インターフェースに対応する`userId`
`notifyTime`	`long`	はい	コールバック時間	コールバック通知時間
`orderCreateTime`	`long`	はい	注文作成時間
`orderId`	`String`	はい	注文番号	プラットフォーム注文番号 (一意)
`status`	`String`	はい	支払い状況	`SUCCESS`、`FAIL`
`type`	`String`	はい	注文タイプ	`PAYMENT` に固定
`userAmount`	`decimal`	はい	ユーザーが実際に支払った金額
`userCurrency`	`String`	はい	ユーザー通貨
`userReceivableAmount`	`decimal`	はい	ユーザー受取可能額
`walletUserId`	`int64`	はい	ウォレットの内部ユーザー ID	OpenAPI 経由でこのアドレスに内部ウォレットの支払いまたは引き出しを行うときに返されます
`sign`	`String`	いいえ	署名値	MD5 署名 (詳細については署名アルゴリズムを参照)

ステータスステータスの説明

ステータス値	説明
`SUCCESS`	完了
`FAIL`	失敗しました

コールバック応答要件

販売者がコールバックを正常に処理した後、次のコンテンツが返される必要があります。

success

システムが文字列 success を受信すると、コールバック処理は成功したとみなされ、再度送信されることはありません。

コールバック再試行メカニズム

次の場合:

応答がありません
返されるコンテンツは success ではありません
HTTPリクエストの例外
サービスタイムアウト

システムは自動的にコールバック通知の送信を再試行します。

最大再試行回数

14次

再試行間隔

繰り返しのコールバックによるビジネスデータの繰り返し処理を避けるために、マーチャントシステムは orderId に従って冪等処理を実装することをお勧めします。

署名の検証

コールバック通知を受信した後、マーチャントはまず署名検証を実行し、検証に合格した後にビジネスロジックを実行する必要があります。署名アルゴリズムは、注文リクエストの署名ルールと完全に一致しています。「2.署名方法」を参照してください。

署名検証プロセス

コールバックパラメータでsignを取得します 2.パラメータからsignを削除します
パラメータに販売者 key を入力します
マーチャント secret を使用して、署名ルールに従って署名を再計算します
コールバック内で計算結果がsignと一致するか比較する

署名検証が成功した後にのみ、注文業務が処理される必要があります。

Java 署名検証の例

public void notify(JSONObject data) {

    log.info("收到回调通知：{}", data.toJSONString());

    String key = "your_key";
    String secret = "your_secret";

    String sign = data.getString("sign");

    data.put("key", key);
    data.remove("sign");

    String calculatedSign = SignUtils.getSign(data, secret);

    if (!calculatedSign.equals(sign)) {
        throw new DxBizException("签名验证失败");
    }
    // 业务处理逻辑
}

クエリパラメータ​

JSON サンプルをリクエスト​

応答データパラメータの説明​

コールバック通知

コールバック アドレスの構成​

コールバックリクエストメソッド​

コールバック データの例​

シナリオ 1: チェーン (他のウォレット) を介してこのアドレスに送金します​

シナリオ 2: 内部ウォレット経由でこのアドレスに送金​

シナリオ 3: Merchant OpenAPI を通じてこのアドレスにお金を引き出す​

コールバックパラメータの説明​

ステータス ステータスの説明​

コールバック応答要件​

コールバック再試行メカニズム​

最大再試行回数​

再試行間隔​